home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr49 / ccl110je.zip / COROUTIN.DOC < prev    next >
Text File  |  1993-06-19  |  7KB  |  153 lines
  1.  
  2.  
  3.                                                                 Page 1
  4.  
  5.     Class Coroutine: an abstract base class for DOS coroutines.
  6.     -----------------------------------------------------------
  7.  
  8.       Author: John English (je@unix.brighton.ac.uk)
  9.               Department of Computing
  10.               University of Brighton
  11.               Brighton BN2 4GJ, England.
  12.  
  13.       Copyright (c) J.English 1993.
  14.  
  15.       Permission is granted to use copy and distribute the
  16.       information contained in this file provided that this
  17.       copyright notice is retained intact and that any software
  18.       or other document incorporating this file or parts thereof
  19.       makes the source code for the library of which this file
  20.       is a part freely available.
  21.  
  22.  
  23.     1. Introduction.
  24.     ----------------
  25.     This class provides a framework for writing DOS coroutines.
  26.     Coroutines allow you to share the available processor time
  27.     between a number of activities; when a coroutine based on
  28.     this class has nothing useful to do, it can call the member
  29.     function "pause" which will allow other coroutines to execute.
  30.     A call to "pause"will return after all the other coroutines
  31.     present in the system have had a chance to execute.
  32.  
  33.     To create a coroutine using this class, you must derive a
  34.     class containing a virtual function "main" which defines
  35.     the code to be executed by your coroutine.  You can then
  36.     declare instances of this class and start them executing
  37.     by calling the member function "run".  Coroutines can be
  38.     terminated by calling the member function "terminate", and
  39.     you can wait for a coroutine to terminate using the member
  40.     function "wait".
  41.  
  42.     If you find this class useful or have any suggestions as to how it
  43.     can be enhanced, please contact the author at one of the addresses
  44.     given above.  E-mail and postcards will both be welcome!
  45.  
  46.  
  47.     2. Deriving a new coroutine class from class Coroutine.
  48.     -------------------------------------------------------
  49.     The constructor for your derived class should invoke the constructor
  50.     for class Coroutine.  The constructor for Coroutine takes a single
  51.     unsigned integer parameter which defines the stack size in bytes
  52.     to be used by the coroutine.  A default stack size of 2048 bytes
  53.     will be assumed if you do not specify otherwise.  Your coroutine
  54.     class must define a member function called "main" which contains
  55.     the application-specific code for your coroutine.  This function
  56.     is defined as follows:
  57.  
  58.         void YourCoroutineClass::main ()
  59.         {
  60.             // application-specific code
  61.         }
  62.  
  63.     Having created a derived coroutine class, you can then declare
  64.     instances of this class in your program.  To start executing a
  65.  
  66.  
  67.                                                                 Page 2
  68.  
  69.     coroutine called "x", simply call the member function "run" as
  70.     follows:
  71.  
  72.         x.run ();
  73.  
  74.     "Run" returns a value of 1 (TRUE) if the coroutine has successfully
  75.     been started, and 0 (FALSE) otherwise.  A result of 0 indicates that
  76.     there was not enough memory to create the coroutine data structures.
  77.  
  78.     Once you have started a coroutine running, it will begin executing
  79.     the member function "main" which you have provided.  When a coroutine
  80.     (or the main program) has nothing to do, it should call the static
  81.     member function "pause" as follows:
  82.  
  83.         Coroutine::pause ();
  84.  
  85.     This allows the next coroutine to execute.  If all coroutines and
  86.     the main program call "pause" at regular intervals, the processor
  87.     time will be shared between each of the coroutines.
  88.  
  89.     Note that since rescheduling only takes place when "pause" is called,
  90.     there is no need for a synchronisation mechanism such as semaphores
  91.     to allow coroutines to communicate.  Coroutines can communicate with
  92.     each other simply by updating shared variables.
  93.  
  94.  
  95.     3. Initialisation and finalisation.
  96.     -----------------------------------
  97.     The coroutine constructor allows you to perform any initialisation
  98.     your coroutine requires.  Note however that the coroutine itself
  99.     does not start executing until "run" is called.  Note that calling
  100.     "run" from inside the constructor is inadvisable, as it will prevent
  101.     further derivations and will also make it difficult to deal with
  102.     errors as indicated by the result returned by "run".
  103.  
  104.     Execution of the coroutine normally ends when the coroutine's main
  105.     function returns.  However, the member function "terminate" can be
  106.     used to terminate a coroutine immediately, as follows:
  107.  
  108.         x.terminate ();     // terminate coroutine "x"
  109.  
  110.     This function should be used with care, as the state of the coroutine
  111.     at the time it is called will unknown.  However, since the coroutine
  112.     will always be suspended in a call to "pause", you can avoid problems
  113.     by ensuring that the coroutine is always in a state where it can be
  114.     safely terminated whenever "pause" is called.
  115.  
  116.     You can also wait for a coroutine to terminate by calling the member
  117.     function "wait":
  118.  
  119.         x.wait ();          // wait for coroutine "x" to terminate
  120.  
  121.     Note that if a coroutine attempts to wait for itself to terminate,
  122.     it will have its wish granted by being terminated immediately.
  123.  
  124.     When you exit from a block where a coroutine has been declared, the
  125.     destructor for that coroutine will be called.  The standard destructor
  126.     waits for the coroutine to terminate and then performs the necessary
  127.     tidying-up.  If your derived class defines a destructor, it will be
  128.     executed BEFORE the standard destructor.  The coroutine may still be
  129.  
  130.  
  131.                                                                 Page 3
  132.  
  133.     active at this point, so you should not do anything which might cause
  134.     the member function "main" to fail.  Destructors should always call
  135.     "wait" to wait for the coroutine to terminate before doing anything
  136.     else.  The standard structure for a destructor should therefore be
  137.     as follows:
  138.  
  139.         MyCoroutine::~MyCoroutine ()
  140.         {
  141.             wait ();    // wait for coroutine to terminate
  142.             ...         // destroy object as necessary
  143.         }
  144.  
  145.     
  146.     4. A plea for feedback.
  147.     -----------------------
  148.     If you use this class, please contact the author via the addresses
  149.     at the beginning; if you don't have e-mail access please send me a
  150.     postcard (I like postcards!) just to let me know you've looked at
  151.     it.  Feel free to suggest enhancements, find bugs or (better still)
  152.     fix them and send me patches.  Happy hacking!
  153.